XmlStackBuilder — API Reference

Kompletní seznam veřejných metod a properties třídy XmlStackBuilder. Všechny metody jsou volatelné z FoxPro přes wwDotnetBridge.

Properties

Obecné

Property Typ Popis
Depth int Aktuální hloubka zásobníku elementů (read-only)
CurrentElement XElement Aktuální element na zásobníku (read-only)
Root XElement Kořenový element (read-only)
CsvDelimiter string Oddělovač pro CSV export validačních chyb (default ";")

HTML generování

Property Typ Default Popis
HtmlDocumentTitle string "" Název dokumentu v HTML záhlaví
HtmlCompanyName string "" Název firmy v HTML záhlaví
HtmlReportPeriod string "" Období sestavy (např. "12/2025")
HtmlOutputMode string "print" Režim: "print" nebo "interactive"
HtmlShowTechnicalNames bool false Zobrazit technické názvy elementů
HtmlFormatNumbers bool true Formátovat čísla s oddělovačem tisíců
HtmlHideEmptyValues bool false Skrýt prázdné hodnoty
HtmlXsdValidationPath string "" Cesta k XSD pro inline validaci
HtmlSectionLabelsPath string "" Cesta k .labels souboru s popisky sekcí (auto-detekce vedle HTML/XML)
HtmlErrorMessage string — Poslední chybová zpráva (read-only)
TemplateWarnings string — Varování z validace JSON šablony (read-only)

Batch, tisk a průběh

Property Typ Default Popis
BatchOutput string "" Batch režim: "" (off), cesta PDF, "PRINTER:", "PRINTER:název"
ShowProgress bool false Zobrazit WinForms dialog s průběhem renderování
PdfFromHtml bool false Dokumenty: PDF přes HTML→WebView2 místo přímého MigraDoc
PrintDialog bool false Zobrazit dialog při tisku (auto-reset po zobrazení)
PrintFromPage int 0 Od stránky (0 = od začátku)
PrintToPage int 0 Do stránky (0 = do konce)
PrintCopies int 1 Počet kopií (1–999)
PrintDuplex int 0 0=default, 1=simplex, 2=oboustranný vertical, 3=horizontal
PrintCollate bool false Kompletovat kopie
BatchPageCount int 0 Počet stránek v batchi (read-only)
BatchDocumentCount int 0 Počet dokumentů v batchi (read-only)

ShowProgress zobrazí WinForms dialog s progress barem, číslem řádku a tlačítkem "Storno" pro přerušení. Dialog běží na samostatném STA threadu — renderování zůstává synchronní. Při zrušení se nastaví HtmlErrorMessage a Render() vrátí false. Property přežívá Reset() i EndBatch().

XML Builder

Metoda Návrat Popis
CreateRoot(elementName) self Vytvoří kořenový element
CreateRootWithNamespace(elementName, namespaceName) self Vytvoří kořen s namespace
Push(elementName) self Přidá child element a vstoupí do něj
PushWithNamespace(elementName, namespaceName) self Push s explicitním namespace
Push(elementName, content) self Push s obsahem (text/číslo)
Pop() self Vystoupí z aktuálního elementu
PopToRoot() self Vystoupí na kořen
PopTo(depth) self Vystoupí na zadanou hloubku
ResetToRoot() void Vystoupí na kořen (void varianta)
AddAttribute(name, value) self Přidá atribut (prázdné přeskočí)
AddOptionalAttribute(name, value) self Přidá volitelný atribut
AddRequiredAttribute(name, value) self Přidá povinný atribut (null → "")
AddAttributes(params (name, value)[]) self Přidá více atributů najednou
SetValue(value) self Nastaví textový obsah elementu
AddElement(elementName) self Přidá prázdný child element
AddElement(elementName, content) self Přidá child element s obsahem
AddElement(elementName, content, attributes[]) self Přidá element s obsahem a atributy
AddElementWithValue(elementName, content) self Přidá element s validací
AddElementWithXmlContent(elementName, xmlContent) self Vloží surové XML potomky (strip VFPData)
AddComment(comment) self Přidá XML komentář
AddCData(data) self Přidá CDATA sekci
AddNamespace(prefix, namespaceName) self Přidá namespace deklaraci
SetDefaultNamespace(namespaceName) self Nastaví výchozí xmlns

Výstup XML

Metoda Návrat Popis
ToDocument() XDocument Vrátí interní XDocument
ToXmlString() string XML jako string
ToFormattedXmlString() string XML s odsazením
SaveToFile(filePath) void Uloží XML do souboru
Reset() void Vymaže XML, zachová batch/print/config

Validace XML

Metoda Návrat Popis
SetValidationEnabled(enabled) void Zapne/vypne validaci
RegisterValidationRule(rule) void Registruje pravidlo (regex, min/max, délka)
RegisterElementNamespace(elemName, nsUri, parent) void Registruje namespace pro element
RegisterElementNs(elemName, nsUri, parent) void Totéž bez overloadu (FoxPro)
RegisterRequiredAttribute(key) void Registruje povinný atribut ("Element:Attr")
GetValidationErrors() List Seznam validačních chyb
GetValidationErrorCount() int Počet chyb
HasValidationErrors() bool Jsou chyby?
GetValidationErrorsAsLog() string Chyby jako textový log
GetValidationErrorsAsCsv() string Chyby jako CSV
ClearValidationErrors() void Vymaže chyby

HTML z XML (opis XML s popisky z XSD)

Metoda Návrat Popis
SaveToHtmlFile(htmlPath, xsdPath) bool Uloží XML jako HTML s popisy z XSD
ToHtmlString(xsdPath) string Vrátí HTML string
SaveToHtmlFileWithValidation(htmlPath, xsdPath) bool HTML s inline XSD validací (zvýrazněné chyby)
SaveXmlFileToHtmlWithValidation(xmlPath, htmlPath, xsdPath) bool HTML z XML souboru s validací
SaveToHtmlFileSingleRow(htmlPath, xsdPath) bool HTML varianta „jeden prvek = jeden řádek" (viz níže)

Režim „jeden prvek = jeden řádek" (SingleRowMode)

Varianta HTML opisu XML, kde je každý atribut nebo leaf element na samostatném řádku se třemi sloupci: název | popis z XSD | hodnota. Popis elementu (pokud je v XSD) se navíc zobrazuje vedle nadpisu sekce kurzívou. Opakující se sekce (více záznamů stejného jména) se rozpadnou na samostatné karty s číslováním #1, #2…

Zapnout lze buď jednorázovou metodou SaveToHtmlFileSingleRow, nebo propertou HtmlSingleRowMode = .T. (režim pak platí i pro SaveToHtmlFileWithValidation a SaveXmlFileToHtmlWithValidation).

Property:

Property Typ Default Popis
HtmlSingleRowMode bool false Zapne režim single-row pro všechny HTML opis metody

Použití z FoxPro:

*--- Varianta 1: jednorázová metoda (režim se po zavolání vrátí zpět) ---
loBuilder.SaveToHtmlFileSingleRow("out.html", "C:\xsd\REGZEC")

*--- Varianta 2: property + existující metody (včetně validace) ---
loBuilder.HtmlSingleRowMode = .T.
loBuilder.SaveToHtmlFileWithValidation("out.html", "C:\xsd\REGZEC")

*--- Z XML souboru (bez interního builderu) ---
loBuilder.HtmlSingleRowMode = .T.
loBuilder.SaveXmlFileToHtmlWithValidation("data.xml", "out.html", "C:\xsd\REGZEC")

Použití v C# (HtmlDataRenderer přímo):

var renderer = new HtmlDataRenderer
{
    SingleRowMode = true,
    XsdValidationPath = @"C:\xsd\REGZEC"  // volitelně inline validace
};
renderer.LoadDescriptionsFromXsd(@"C:\xsd\REGZEC");
var doc = XDocument.Load(xmlPath, LoadOptions.SetLineInfo);
renderer.RenderToFile(doc, htmlPath);

CSS třídy výstupu: .single-row-table, .sr-name, .sr-desc, .sr-val, .section-desc, .single-row-card. | ValidateTableReportJson(jsonMetadata) | string | Validuje JSON šablonu tabulkové sestavy | | ValidateDocumentJson(jsonMetadata) | string | Validuje JSON šablonu dokumentu |

Tabulkové sestavy (HTML)

Metoda Návrat Popis
ToTableReport() string HTML sestava (auto-detekce struktury)
ToTableReportWithHeader(title, company, filter) string HTML sestava se záhlavím
ToTableReportWithMetadata(jsonMetadata) string HTML sestava s JSON šablonou
SaveTableReportToFile(htmlPath, title, company, filter) bool Uloží HTML sestavu
SaveTableReportToFileWithMetadata(htmlPath, jsonMetadata) bool Uloží s JSON šablonou (string)
SaveTableReportToFileWithMetadataFile(htmlPath, jsonFilePath) bool Uloží s JSON ze souboru (UTF-8)
GenerateTableReportMetadata() string Vygeneruje JSON šablonu z XML (light)
GenerateTableReportMetadataFull() string Vygeneruje kompletní JSON šablonu

Dokumenty — faktury, dodací listy (HTML)

Metoda Návrat Popis
ToDocumentHtml(jsonMetadata) string HTML dokument z JSON šablony
SaveDocumentToFile(htmlPath, jsonMetadata) bool Uloží HTML dokument (JSON string)
SaveDocumentToFileFromJson(htmlPath, jsonFilePath) bool Uloží HTML dokument (JSON ze souboru)

Unified Render API

Univerzální metody — auto-detekce typu šablony (tabulka/dokument) a formátu výstupu (HTML/PDF/XLSX) z přípony souboru.

Metoda Návrat Popis
Render(outputPath, jsonOrFile) bool Renderuje z interního XML builderu
RenderFromFiles(outputPath, jsonOrFile, xmlOrFile) bool Renderuje z externích souborů/stringů

outputPath: přípona určuje formát — .html, .pdf, .xlsx, PRINTER: (tisk) jsonOrFile: začíná { → JSON string, jinak → cesta k souboru xmlOrFile: začíná < → XML string, jinak → cesta k souboru

PDF generování

Přes WebView2 (HTML → PDF)

Metoda Návrat Popis
SaveHtmlToPdf(htmlPath, pdfPath) bool Konvertuje existující HTML na PDF
SaveDocumentToPdf(pdfPath, jsonMetadata) bool Dokument → HTML → PDF
SaveDocumentToPdfFromJson(pdfPath, jsonFilePath) bool Dokument → PDF (JSON ze souboru)
SaveTableReportToPdf(pdfPath, jsonMetadata) bool Sestava → HTML → PDF
IsPdfAvailable() bool Je WebView2 Runtime nainstalován?

Přímé PDF (MigraDoc) — bez WebView2, vysoký výkon

Metoda Návrat Popis
SaveTableReportToPdfDirect(pdfPath, jsonMetadata) bool Sestava → PDF přímo (JSON string)
SaveTableReportToPdfDirectFromFile(pdfPath, jsonFilePath) bool Sestava → PDF (JSON ze souboru)
SaveDocumentToPdfDirect(pdfPath, jsonMetadata) bool Dokument → PDF přímo (JSON string)
SaveDocumentToPdfDirectFromFile(pdfPath, jsonFilePath) bool Dokument → PDF (JSON ze souboru)

XLSX generování (ClosedXML)

Metoda Návrat Popis
SaveTableReportToXlsx(xlsxPath, jsonMetadata) bool Sestava → Excel (JSON string)
SaveTableReportToXlsxFromFile(xlsxPath, jsonFilePath) bool Sestava → Excel (JSON ze souboru)

FRX konvertor

Metoda Návrat Popis
ConvertFrxToJson(frxXml) string FRX XML → JSON šablona (auto-detekce typu)
ConvertFrxToJsonFile(frxXmlPath, outputJsonPath) bool FRX soubor → JSON soubor (auto-detekce)
ConvertFrxToTableReportJson(frxXml) string FRX → JSON (vynuceně tabulka)
ConvertFrxToDocumentJson(frxXml) string FRX → JSON (vynuceně dokument)
ConvertFrxToTableReportJsonFile(frxXmlPath, outputJsonPath) bool FRX soubor → JSON soubor (vynuceně tabulka)
ConvertFrxToDocumentJsonFile(frxXmlPath, outputJsonPath) bool FRX soubor → JSON soubor (vynuceně dokument)
GenerateSampleXmlFromJson(jsonTemplate) string JSON šablona → vzorové XML
GenerateSampleXmlFromJsonWithRoot(jsonTemplate, rootName) string Vzorové XML s vlastním kořenem
GenerateFoxProCodeFromJson(jsonTemplate) string JSON šablona → FoxPro PRG kód
GenerateFoxProCodeFromJsonWithRoot(jsonTemplate, rootName) string PRG s vlastním kořenem
ConvertFrxToAllFiles(frxXmlPath, outputFolder) bool FRX → JSON + XML + PRG (auto-detekce)
ConvertFrxToTableReportAllFiles(frxXmlPath, outputFolder) bool FRX → JSON + XML + PRG (vynuceně tabulka)
ConvertFrxToDocumentAllFiles(frxXmlPath, outputFolder) bool FRX → JSON + XML + PRG (vynuceně dokument)
ExtractLiteralsFromJson(jsonTemplate) string Extrahuje přeložitelné texty jako XML
ExtractLiteralsFromJsonFile(jsonFilePath) string Totéž ze souboru

Auto-detekce typu (table/document) z FRX někdy klasifikuje špatně. Varianty s vynuceným typem (TableReport/Document v názvu) toto obcházejí.

Generování JSON šablon z cursor schema

Generování JSON šablon pro tabulkové sestavy přímo z definice FoxPro kurzoru (cursor schema). Vstupem je string se schématem tabulky a volitelné parametry — výstupem je JSON s odhadnutými šířkami sloupců v mm.

Metoda Návrat Popis
GenerateColumnsFromSchema(cursorSchema, options) string Vrátí JSON fragment s columns a printColumns
GenerateReportFromSchema(outputJsonPath, cursorSchema, options) bool Zapíše kompletní JSON report šablonu do souboru

cursorSchema: Dva podporované formáty:

options: Řetězec "key1:value1,key2:value2,..." s konfigurací:

Klíč Default Popis
dataFontPt 8 Velikost fontu datových buněk (pt)
pageSize A4 Formát papíru: A4, A3
orientation auto portrait, landscape, auto
maxDecimal 2 Max počet desetinných míst
maxLenString 20 Max šířka textových sloupců (znaky)
groups — Skupiny: stredisko;ucet (; odděluje). Prefix - = sestupné řazení skupiny (např. -datum;stredisko) — emituje "sortDesc": true
noTotalColumns — Sloupce bez součtů: id;doklad (; odděluje)
sumExpressions — Explicitní agregace přebíjející auto-generaci. Formát: pole=FUNC;pole2=FUNC2 (např. castka=SUM;pocet=COUNT;cena=AVG). Podporované funkce: SUM, COUNT, AVG, MIN, MAX. Bez =FUNC se použije SUM.
grandTotal true Celkový souhrnný řádek (Celkem). false = neemitovat section-level sumLabel/sumExpressions, zachovat group-level.
rowNumberLabel — Vlastní popisek sloupce s čísly řádků (default #). Emituje se jen když rowNumbers ≠ false.
element data Název XML elementu se záznamy
title — Nadpis sestavy (podporuje {element.field})
tfiltr — Filtr sestavy (podporuje {element.field})
culture cs-CZ Kultura pro formátování
lang cs Jazyk popisků: cs, sk, en, de. Ovlivní default sumLabel, groupSumPrefix, pageLabel, printedLabel.
sumLabel Celkem (cs) Popisek souhrnného řádku — přebije lang.
groupSumPrefix Celkem za (cs) Prefix pro group sum row ({prefix} {groupValue}) — přebije lang.
pageLabel Strana … z … (cs) Formát pageHeader — přebije lang.
printedLabel Vytištěno: (cs) Footer text vytištění — přebije lang.
rowNumbers false Číslování řádků: false, global, group

Escape sekvence v options stringu

Options string používá : a , jako oddělovače. Pro hodnoty obsahující tyto znaky použijte zpětné lomítko:

Sekvence Význam
\, Literál čárky v hodnotě
\: Literál dvojtečky v hodnotě
\\ Literál zpětného lomítka

Příklady:

title:Přehled faktur\, Q1 2026,orientation:landscape
tfiltr:Datum\: 2026-01-01..2026-03-31
sumLabel:Celkem\, netto,lang:cs

Lokalizační defaulty

lang sumLabel groupSumPrefix pageLabel printedLabel
cs Celkem Celkem za Strana … z … Vytištěno:
sk Spolu Spolu za Strana … z … Vytlačené:
en Total Total for Page … of … Printed:
de Gesamt Summe für Seite … von … Gedruckt:

Individuální sumLabel/groupSumPrefix/pageLabel/printedLabel v options vždy přebijí default z lang.

Tisk

Jednorázový tisk

Metoda Návrat Popis
PrintWithDialog(jsonOrFile) bool Tisk s dialogem (XML z builderu)
PrintFromFilesWithDialog(jsonOrFile, xmlOrFile) bool Tisk s dialogem (externí soubory)
PrintSilent(jsonOrFile, printer, fromPage, toPage) bool Tichý tisk (XML z builderu)
PrintFromFilesSilent(jsonOrFile, xmlOrFile, printer, from, to) bool Tichý tisk (externí soubory)
PrintPdfFile(pdfPath, printerName) bool Tisk PDF přes SumatraPDF

Utility

Metoda Návrat Popis
GetAvailablePrinters() string Seznam tiskáren (oddělené \n)
GetDefaultPrinter() string Název výchozí tiskárny
GetReportPageCount(jsonOrFile) int Počet stránek sestavy (−1 = chyba)
GetPrinterCapabilities(printerName) string Schopnosti tiskárny (duplex, papír, zásobník, barva)

Batch tisk / PDF

Metoda Návrat Popis
EndBatch() int Ukončí batch (sloučí PDF / vyčistí). Vrátí počet stránek.
ResetPrint() void Resetuje tiskové properties na default

Batch se řídí přes property BatchOutput — viz sekce Properties.

Generování dokumentových šablon z XML dat

Automatické generování JSON šablon pro dokumentový renderer ("renderer": "document") z XML dat. Heuristická analýza XML struktury — detekce archetypu (faktura/dopis/protokol), klasifikace elementů, generování bloků.

Metoda Návrat Popis
GenerateDocumentFromXml(options) string Vygeneruje JSON šablonu z XML v builderu. Vrátí JSON string.
GenerateDocumentFromXmlToFile(outputJsonPath, options) bool Vygeneruje JSON šablonu z XML v builderu a uloží přímo do souboru (UTF-8).
GenerateDocumentFromXmlFile(outputJsonPath, xmlFilePath, options) bool Vygeneruje JSON šablonu z externího XML souboru a uloží do souboru (UTF-8).

options: Řetězec "key1:value1,key2:value2,..." s konfigurací (nebo "" pro výchozí):

Klíč Default Popis
type auto Archetyp: faktura, dopis, protokol, formular, dokument. Auto = heuristická detekce.
title "" Nadpis dokumentu
culture cs-CZ Kultura pro formátování (čísla, datumy)
pageMarginMm 8 Okraje stránky v mm
style "" Styl: bordered (rámeček kolem bloků)

Auto-detekce archetypu (pokud type není zadán):

Archetyp Podmínka
faktura Vlastní firma + protistrana + tabulka s celkovým součtem
dopis Vlastní firma + protistrana, bez tabulky
protokol Vlastní firma + tabulka, bez protistrany
formular Tabulka bez vlastní firmy a protistrany (bankovní formuláře, příkazy k úhradě)
dokument Fallback — bloky v pořadí elementů

Příklad:

*--- Vrátí JSON string ---
lcJson = loBuilder.GenerateDocumentFromXml("type:faktura,title:Faktura")

*--- Uloží přímo do souboru (řeší cp1250/UTF-8) ---
loBuilder.GenerateDocumentFromXmlToFile("C:\json\faktura.json", "type:faktura,title:Faktura")

*--- Z externího XML souboru ---
loBuilder.GenerateDocumentFromXmlFile("C:\json\faktura.json", "C:\data\data.xml", "")

VS Code editor

Metoda Návrat Popis
OpenReportEditor(jsonPath, xmlPath) bool Otevře VS Code s IntelliSense + live preview
OpenReportEditorWithSchemas(jsonPath, xmlPath, schemaFolder) bool Totéž s explicitní cestou ke schématům
OpenReportEditorNew(jsonPath, xmlPath, templateType) bool Pokud JSON neexistuje nebo je prázdný, vygeneruje výchozí šablonu z XML a otevře VS Code

OpenReportEditorNew — pre-fill + editor v jednom kroku:

Parametr Popis
jsonPath Cesta k JSON šabloně (nemusí existovat)
xmlPath Cesta k XML datům (pro analýzu struktury)
templateType "document" — dokumentová šablona (heuristická), "table" — minimální tabulková šablona

Pokud JSON soubor existuje a není prázdný, otevře se bez přegenerování (existující práce se nepřepisuje).

Příklad:

*--- Nový dokument (faktura) ---
loBuilder.OpenReportEditorNew("C:\json\nova_faktura.json", "C:\data\sample.xml", "document")

*--- Nová tabulková sestava ---
loBuilder.OpenReportEditorNew("C:\json\nova_sestava.json", "C:\data\sample.xml", "table")

VS Code snippety: Při otevření editoru se automaticky generuje .vscode/blocks.code-snippets s 26 snippety. Prefix doc- pro dokumentové bloky (header, info-grid, table, total, text, signature, separator, spacer, image, qr, columns, form-table, page-break), prefix rep- pro tabulkové struktury (column, column-expr, column-template, group, sum, sumrows, footer-row, lookup, row-style, header-rows, page-header, page-footer, section).

Markdown → HTML

Metoda Návrat Popis
RenderMarkdownToHtml(markdownContent, outputPath) bool Markdown string → HTML soubor
RenderMarkdownFileToHtml(markdownPath, outputPath) bool Markdown soubor → HTML soubor

Přímý export XML → JSON / CSV / XML (bez šablony)

Třída DataExporter — statická utilita pro rychlý export XML dat do běžných formátů bez nutnosti JSON šablony. Ideální pro User Reports, kde uživatel chce data rovnou do Excelu nebo systému třetí strany.

Export z XML stringu

Metoda Návrat Popis
DataExporter.ExportToJson(outputPath, xmlString, out errorMessage) bool XML → JSON (type-aware: čísla, boolean bez uvozovek)
DataExporter.ExportToCsv(outputPath, xmlString, out errorMessage) bool XML → CSV (UTF-8 BOM, ; oddělovač, RFC 4180 escape)
DataExporter.ExportToXml(outputPath, xmlString, out errorMessage) bool XML → reformátované XML (UTF-8 deklarace, odsazení)

Export z XML souboru

Metoda Návrat Popis
DataExporter.ExportFileToJson(outputPath, xmlFilePath, out errorMessage) bool Načte XML soubor a exportuje do JSON
DataExporter.ExportFileToCsv(outputPath, xmlFilePath, out errorMessage) bool Načte XML soubor a exportuje do CSV
DataExporter.ExportFileToXml(outputPath, xmlFilePath, out errorMessage) bool Načte XML soubor a reformátuje do UTF-8

Chování

Příklad

string err;
bool ok = DataExporter.ExportToCsv(@"C:\export\faktury.csv", xmlString, out err);
if (!ok) MessageBox.Show(err);

*-- Z FoxPro přes wwDotnetBridge
LOCAL lcErr
lcErr = ""
llOk = loBridge.InvokeStaticMethod("XmlStackBuilder.Core.DataExporter", "ExportFileToCsv", ;
    "C:\export\faktury.csv", "C:\data\faktury.xml", @lcErr)

Poznámky